home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / slpack2.zip / SLPACK.DOC next >
Text File  |  1991-11-02  |  12KB  |  312 lines
  1.  
  2.                                   SLPACK
  3.               Searchlight Message Base Pack/Optimize Utility
  4.                        Version 2.15, November, 1991
  5.                  (c) Copyright 1991 Searchlight Software
  6.  
  7.  
  8. INTRODUCTION
  9. ------------
  10. SLPACK is a message base packing and optimization utility for Searchlight 
  11. 2.15 message subboards. SLPACK operates on subboard header (HDR) and/or 
  12. message (MSG) files, and performs three main tasks:
  13.  
  14. (1) Optimization -- Records in the data files are physically sorted into
  15.     sequential order, improving access times.
  16.  
  17. (2) Packing -- Unused records are purged from the data files and the files
  18.     are physically shrunk to release unused disk space back to DOS.
  19.  
  20. (3) Renumbering -- Messages can optionally be renumbered in sequential order
  21.     starting with 1, when packing the subboard header files.
  22.  
  23. SLPACK is a command-line driven program; it can operate on one, several, or 
  24. all subboards at once. Command line options are shown below.
  25.  
  26.  
  27. SYNTAX
  28. ------
  29. The command line syntax for running SLPACK is as follows:
  30.  
  31.   SLPACK [Options...] [Subboards...]
  32.  
  33. "Options" can be one or more of the option switches described below, and 
  34. "Subboards" can be one or more valid subboard names. Subboard names are 
  35. required unless the /A (All) switch is used. If no options or subboard names 
  36. are specified, then SLPACK displays a brief summary of its options:
  37.  
  38.   /M       Pack message (MSG) files only
  39.   /H       Pack header (HDR) files only
  40.   /R       Renumber messages on subboard
  41.   /N       Skip confirmation prompt
  42.   /A       Pack all subboards
  43.   /S       Scan subboards before packing
  44.   /Fn[,m]  Free records for header [,message] files
  45.   /Pn      Pack only if 1st message >= n
  46.  
  47. Note: Before running SLPACK, please see the CAUTION section below.
  48.  
  49.  
  50. OPTIONS
  51. -------
  52. Option /M -- Pack Message Files Only
  53.  
  54. If the /M switch is given, SLPACK will pack only the message (*.MSG) files 
  55. associated with the given subboards. Otherwise, both the header and message 
  56. files are packed.
  57.  
  58. The message file is usually larger than the header file; therefore, packing 
  59. the message file only provides a good deal of optimization in a shorter 
  60. amount of time than if both files are packed. However, packing the header 
  61. file is required if you want to renumber messages.
  62.  
  63. Example: SLPACK /M GENERAL SLBBS-R
  64.  
  65.  
  66. Option /H -- Pack Header Files Only
  67.  
  68. This option causes just the header files of the specified subboards to be 
  69. packed and optimized. Message files are not affected.
  70.  
  71. Example: SLPACK /H GENERAL SLBBS-R
  72.  
  73.  
  74. Option /R -- Renumber Messages
  75.  
  76. The renumber option causes messages to be renumbered sequentially, with the 
  77. first message number equal to 1 and the last number equal to the number of 
  78. messages on the subboard.
  79.  
  80. Renumbering can only occur if the header file is packed; no renumbering will 
  81. take place if the /M option is also selected.
  82.  
  83. The renumber option also causes the high message pointers contained in the 
  84. subboard's member files to be updated.
  85.  
  86. Example: SLPACK /R GENERAL SLBBS-R
  87.  
  88.  
  89. Option /N -- Skip Confirmation Prompt
  90.  
  91. When /N is NOT specified, SLPACK displays a warning message before it begins 
  92. to run, and requires that you type "Y" and "Enter" to continue. If the /N 
  93. switch is specified, this confirmation prompt is skipped.
  94.  
  95. Use /N when you run SLPACK in an unattended environment (such as in a batch 
  96. file or as part of an event).
  97.  
  98. Example: SLPACK /R /N SLBBS-R
  99.  
  100.  
  101. Option /A -- Pack All Subboards
  102.  
  103. The /A switch causes SLPACK to operate on all subboards in your system, 
  104. instead of just the subboards specified on the command line. When /A is 
  105. used, no subboard names need be specified.
  106.  
  107. Example: SLPACK /R /N /A
  108.  
  109.  
  110. Option /S -- Scan Subboards Before Packing
  111.  
  112. When the /S switch is enabled, SLPACK does a repair scan (equivalent to the 
  113. F3 utility functions in the SETUP program) before packing each file. 
  114.  
  115. This option is recommended, especially when running SLPACK in an unattended 
  116. mode (such as when SLPACK is part of an event). Packing a subboard involves 
  117. rearranging every record in the file; files which contain even one bad 
  118. pointer or corrupt record can result in the entire subboard becoming corrupt 
  119. and even in SLPACK aborting. Using the /S switch assures that each subboard
  120. file is checked for consistency before it is packed.
  121.  
  122. If you are reasonably sure that a subboard is not corrupted, you can omit 
  123. the /S switch, which will speed up SLPACK.
  124.  
  125. Note that the /S switch is not a substitute for making a backup; it is 
  126. always recommended that a backup of the files to be packed be made before 
  127. running SLPACK.
  128.  
  129.  
  130. Option /Fn[,m] -- Specify Free Record Counts
  131.  
  132. The /F command, which is followed by one or two numeric parameters, 
  133. specifies the number of free records to be appended to the end of the header 
  134. and message files after packing is complete.
  135.  
  136. By default, SLPACK removes all free records from these files when it packs 
  137. them; if /F is specified, then SLPACK appends the requested number of free 
  138. records to the end of the files. Preallocated free records help reduce file 
  139. fragmentation and increase speed when saving new messages to the file.
  140.  
  141. Note that free record parameters have no effect unless the respective file 
  142. is actually packed.
  143.  
  144. Example: SLPACK /F30,100 SLBBS-R     (30 free header & 100 free message recs)
  145.          SLPACK /F40 /H SLBBS-R      (40 free header records)
  146.          SLPACK /F0,200 /M SLBBS-R   (200 free message records)
  147.  
  148.  
  149. Option /Pn -- Check 1st Message Before Packing
  150.  
  151. If the /P option is used, followed by a numeric parameter, then SLPACK only 
  152. packs subboards where the first message on the subboard is greater than or 
  153. equal to the parameter given. For example, if /P100 is specified on the 
  154. command line, then only subboards where the first message on the sub is 
  155. equal to or greater than 100 are packed.
  156.  
  157. Used in conjunction with the /R option, /P allows you to monitor subboards 
  158. which have high turnover volumes and renumber these subs only when the 
  159. oldest message number reaches a certain level. For example, suppose you have 
  160. a subboard which can contain a maximum of 1000 messages, has auto-purge 
  161. enabled, and you prefer that the highest message number does not exceed 
  162. 1500. To accomplish this automatically, you could execute the following 
  163. command on a regular basis:
  164.  
  165.   SLPACK /R /P500 SLBBS-R
  166.  
  167. The value of "500" is chosen for the /P parameter because 500 plus the 
  168. subboard maximum messages (1000) equals the message number preference of 
  169. 1500. It should be noted that if messages are deleted from the subboard 
  170. (other than the earliest messages) or if purge protection is enabled for any 
  171. message, then the high message number may exceed 1500 before the lowest 
  172. message number exceeds 500 and the renumber operation takes place.
  173.  
  174.  
  175. MESSAGES
  176. --------
  177. SLPACK will display the following progress messages as it runs:
  178.  
  179. Packing Subboard: NAME
  180. Packing/Renumbering Subboard: NAME
  181.  
  182.   The "Packing" or "Packing/Renumbering" message tells you which subboard is 
  183.   currently being packed or renumbered.  
  184.  
  185. Performing Safety Scan...
  186.  
  187.   If the /S switch is used, this message appears while SLPACK is performing
  188.   the initial repair scan of the file before packing it.
  189.  
  190. Header File: Reading, Sorting, Done.
  191.  Rebuilding Indexes:
  192.  Rebuilding Threads:
  193. Rebuilding Free List:
  194.  
  195.   These messages follow the progress of the header file repacking, if that
  196.   option has been selected. 
  197.  
  198. Expanding to nnn Free Records...
  199.  
  200.   If the /F option is used, this message appears to report that the file
  201.   is being expanded.
  202.  
  203. Updating Member Records...
  204.  
  205.   This message appears during a renumber (/R) function while the member
  206.   file is being updated.
  207.  
  208. Msg File: Reading, Sorting, Done.
  209. Rebuilding Free List:
  210. Expanding to nnn Free Records...
  211.  
  212.   These messages follow the progress of the message file packing process.
  213.   The "Expanding" message appears only if a free record count for the 
  214.   message file has been specified with /F.
  215.  
  216. Skipped (1st message number = nnn)
  217.  
  218.   This message indicates that a particular subboard is not being packed, 
  219.   because the /P parameter has been used and the first message on the 
  220.   subboard is less than the target value.
  221.  
  222. Insufficient Memory Available (nnn bytes needed)
  223.  
  224.   Not enough memory is available to pack this subboard. See memory 
  225.   requirements, below.
  226.  
  227. Cannot Open Subboard:
  228.  
  229.   Indicates that the subboard cannot be opened. Check the subboard name and
  230.   its data files path.
  231.  
  232.  
  233. CAUTIONS
  234. --------
  235. SLPACK rewrites and rearranges the entire message and header files of the 
  236. subboards it packs. Because of the way in which it operates, SLPACK is 
  237. extremely sensitive to power failures, corrupt files, bad disk sectors, and 
  238. other such problems which may occur during its operation. In order to 
  239. prevent data loss, we stronly urge you to follow these precautions: 
  240.  
  241. (1) BACK-UP ALL SUBBOARD FILES BEFORE PACKING THEM. If an error occurs 
  242.     during SLPACK's operation, it should be assumed that the subboard which
  243.     was open at the time of the error is corrupted, and needs to be restored 
  244.     from the backup copy.  
  245.  
  246. (2) Do not disturb SLPACK once it begins to run. Any attempt to abort
  247.     SLPACK will result in a corrupted subboard. The same is true if SLPACK
  248.     should be interrupted by a system failure such as a reboot, power
  249.     failure, bad disk sector, etc.
  250.  
  251. (3) In multinode systems, no other nodes should be active while SLPACK is 
  252.     running. Either shut your other nodes down manually or, if SLPACK runs 
  253.     as an event, make sure the other nodes are idle while it runs.
  254.  
  255. (4) SLPACK will fail if it tries to pack a subboard which contains corrupted
  256.     data files and the /S command line switch is not specified. Should 
  257.     this occur, try to repair the subboard via the SETUP program repair 
  258.     functions. If this fails, then restore the subboard from a backup file, 
  259.     and pack it again, specifying the /S switch on the SLPACK command line.
  260.  
  261.  
  262. EXIT CODES
  263. ----------
  264. SLPACK will return one of three exit codes (errorlevels) when it completes:
  265.  
  266. Errorlevel 0 -- Indicates that no errors occured and all requested 
  267.   operations were carried out successfully.
  268.  
  269. Errorlevel 1 -- Indicates that SLPACK has done nothing, for one of the 
  270.   following reasons:
  271.  
  272.    A. No command line parameters were specified.
  273.    B. SLPACK could not open the CONFIG.SL2 file. Be sure that CONFIG.SL2
  274.       is either in the current directory, or pointed to by SET SLBBS=.
  275.    C. You answered "N" to the confirmation prompt.
  276.  
  277. Errorlevel 2 -- Indicates that one or more operations failed, because of 
  278.   the following reasons:
  279.  
  280.   A. Can't open subboard: a subboard name given on the command line was
  281.      incorrect, or the subboard files could not be located and opened.
  282.   B. Not enough RAM for requested operation. See RAM note below.
  283.  
  284. Note that Errorlevel 2 errors do not cause SLPACK to terminate immediately. 
  285. It will continue to run and process as many subboards as possible.
  286.  
  287.  
  288. RAM REQUIREMENTS
  289. ----------------
  290. SLPACK requires a significant amount of memory to pack large message bases. 
  291. If insufficient memory is available to pack a particular subboard, SLPACK 
  292. will skip that subboard and display an error message. It will also exit with 
  293. an error level of 2.
  294.  
  295. Here is how you can compute the memory required to pack a particular 
  296. subboard:
  297.  
  298.   (1) Take the DOS file size of the header (*.HDR) file, subtract 8332,
  299.       and divide by 256. If you are using the renumber (/R) option, multiply
  300.       this result by 6. Otherwise, multiply it by 2.
  301.  
  302.   (2) Take the DOS file size of the message (*.MSG) file, subtract 140,
  303.       and divide by 128.
  304.  
  305.   (3) Take THE LARGER OF the two numbers above and add 67,000. This is the
  306.       approximate amount of free DOS memory that needs to be available 
  307.       before you can run SLPACK on this subboard.
  308.  
  309.  
  310. ------
  311.  
  312.